/*
 * OpenParts
 * A dynamic-loading components framework for GWT
 * Copyright (C) 2011 Christophe Bouthier  [chris{AT}binary-gastronome{DOT}fr]
 *
 * This work is partially based on work I have done at INRIA (http://www.inria.fr) 
 * in the context of the Qualipso European Project (http://qualipso.org/),
 * The work done at INRIA is Copyright (C) 2006-2011 INRIA
 *
 * This work is distributed under the LGPL version 3
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License version 3
 * as published by the Free Software Foundation. See the GNU
 * Lesser General Public License in LGPL.txt for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package fr.openparts.OpenParts.client.annotations;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Marks methods that will be registered in {@link fr.openparts.OpenParts.client.OPBinding} as callbacks for handling events dispatched on the event bus. The
 * annotation can take a String or an array of String as parameters, that will represent the specific event the callback is registering for. Passing no
 * arguments will register the callback for all events. Several methods can be annotated, as long as they don't register on the same events. As an exception, if
 * some callbacks are registered on specific events, a callback registered for all events (with no parameters to its annotation) will only receive events that
 * are NOT already received by other callbacks. If there are several callbacks registered for all events, or if several callbacks are registering on the same
 * event, then a UnableToCompleteException is thrown.
 * <p>
 * For example:
 * <p>
 * <code>&#64;OPEventHandler</code><br>
 * will register the callback for all events
 * <p>
 * <code>&#64;OPEventHandler("SPECIFIC_EVENT")</code><br>
 * will register the callback for the event "SPECIFIC_EVENT"
 * <p>
 * <code>&#64;OPEventHandler({"SPECIFIC_EVENT_1", "SPECIFIC_EVENT_2"})</code><br>
 * will register the callback for both events "SPECIFIC_EVENT_1" and "SPECIFIC_EVENT_2"
 * <p>
 * <code>
 * &#64;OPEventHandler("SPECIFIC_EVENT_1")<br>
 * [...]<br>
 * &#64;OPEventHandler("SPECIFIC_EVENT_2")<br>
 * [...]<br>
 * &#64;OPEventHandler<br>
 * </code> will register the first callback for event "SPECIFIC_EVENT_1", the second callback for event "SPECIFIC_EVENT_2", and the last callback for all events
 * that are neither "SPECIFIC_EVENT_1" not "SPECIFIC_EVENT_2".
 * <p>
 * A callback method should take two parameters, one of type String (the event), and one of type OPParams (parameters). If this annotation is put on a method
 * that doesn't have the correct signature, an UnableToCompleteException is thrown.
 * 
 * @author Christophe Bouthier [chris{AT}binary-gastronome{DOT}fr]
 * @creation.date 18 December 2009
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface OPEventHandler {

    /**
     * The specific event or array of specific events that will be registered for the annotated method.
     */
    String[] value() default {};
}
